Thank you for taking the trouble to try this program out. We hope you like it.
Note: this file is formatted and is best read with SimpleText and not TeachText.
Note: this file is not read-only so that you can easily copy the text if you want to. For example, you can copy the email addresses and URLs. Please don’t modify this file or distribute modified versions.
Note: you should scroll up and down a pageful at a time so that the pictures will appear properly. If the pictures don’t appear, you can make them appear by scrolling up a page and then back down a page.
This software is copyrighted material and therefore you are not allowed to modify this software or its documentation in any way, shape or form, nor can you sell it for your own profit. You may only charge a reasonable fee for the cost of distributing it. See the Distribution section below for information about how and on what IIe may be distributed.
Contents
The documentation for IIe comes in 4 files. Their contents are:
1. Read me first
What is it? - description, features, requirements, compatibilty, and performance issues
Description
Features
Hardware and software requirements
Compatibility
Performance issues
Installation and setup
Simple installation/setup
Tips
Frequently Asked Questions (FAQ)
2. Instructions
The Apple //e window
The display area
The //e screen
The icon buttons
Function keys
Graphics modes
Disk inserting/removing
Using real disks
Using disk images
How to insert and remove disks and disk images
Loading and saving information - memory images
Emulator instructions
Default settings
Starting up the emulator
The Reset key
The Keyboard
Paddles and buttons
Debugger instructions
3. Configuring IIe
General pane
65c02 pane
Memory pane
Video pane
Sound pane
Keyboard pane
Joystick/Mouse pane
Printing pane
5 1/4" Disks pane
Other Disks pane
Slots pane
4. Other stuff
Cost/fee and registration
Version history
Future version features
Distribution
Contacting the author
Other software by Vincent
Disclaimer
2. Instructions
It’s assumed that you know how to use an Apple II computer. That is, you’re aware of how to switch it on, insert a disk, boot a disk, remove a disk, use the keyboard and use the joystick. If you know these things then you’ll find using IIe virtually the same as using an Apple //e except that the disk “insertion” and “removal” activities are virtual instead of real (unless you insert a real floppy disk into your Mac in which case it’s real - hmmm, are you confused yet?).
If you don’t know how to use an Apple II, just try using IIe anyway, but please don’t send e-mail asking for this kind of help. Instead, trying posting a message to an Apple II message board. Be polite and explain your ignorance of the Apple II. There should be some kind soul to help you out. If you’re on the internet, try the USENET newsgroups such as ‘comp.sys.apple2.<something>’ or ‘comp.emulators.apple2’.
The following instructions pertain only to features specific to this emulator.
The Apple //e window
This window is divided into several areas:
The display area
At the top is the status display area. It shows you the disk drive lights and which slot/drive they belong to and what image files you have loaded into them. To insert or remove a disk, you can click on the disk image’s name. With more cards installed in the //e, you will see more icons and names in this area (2 for the UniDisk/Hard Disk card (although 4 is possible), 1 for the memory card, 2 for the MacProDOS card). At the bottom right of the status area is the ‘Soft caps lock’ status line. You can activate the Soft caps lock feature from the IIe Preferences window (see the document “3. Configuring IIe” for instructions on how to do this).
The //e screen
At the bottom left, of course, is the //e’s display area which does the function of a real //e’s video monitor. You cannot select anything in this area but you can copy the contents of the //e screen to the Mac clipboard from the Edit menu.
The icon buttons
At the bottom right are eight useful icons to make it easier for you to use IIe. They are:
• “Insert… F5” lets you select disk images, memory images, and folders for use in a //e drive
• “Remove… F6” lets you remove a disk image from a //e drive. Note that if you insert a disk image into a drive that already has a disk image in it, the old image is closed first.
• “Reset” simulates a press of the //e’s reset key (you can also achieve the same effect by pressing control-delete on your Mac keyboard). This icon is disabled is the //e is off or not running).
• “Go F15” or “Stop F15” starts and stops the //e (freezes and runs it). This icon can also function as an on/off switch such that clicking it would be the same as turning off a real //e. When configured in this manner, it will be displayed as “On F15” and “Off F15”. See the “3. Configuring IIe” for instructions on how to configure it to do this.
• “Prefs… F7” opens the IIe Preferences window. If it has not been previously opened, it is opened at the top-most pane, otherwise it is opened at the most recent pane.
• “Slots…•-F7” opens the IIe Preferences window at the Slots pane to let you change the slots. However, changing the slots will not take effect until you quit IIe and start it up again.
• “Mono F13” and “Colour F13” changes the screen display from monochrome to colour and vice versa. You can also option-click the icon to change depths from 8 -> 1 bit depth, 1 -> 4 bit depth, and 4 -> 8 bit depth. You can also control-click it to change the display: if you’re in monochrome mode, it changes the monochrome-white colour from white -> green, green -> amber, amber -> white; if you’re in colour mode, it does nothing except in double hires mode in which case it will display a sharpened image (but this mode is slower than the normal unsharpened image).
• “Interrupt” halts the emulation at whatever instruction it is currently at and displays that in the debugger window. Don’t use this icon unless you really need to, or unless you know what you are doing. Why use it? Well it’s handy if you know 65c02 assembly and want to see what the processor is doing. Eg, “is it hanging or still reading the disk? I know! I’ll check by interrupting it!” Warning: the debugger window is still in development and as such is still very much “raw” in its functioning.
Function keys
If you have an extended keyboard, you can also use the F-keys at the top of the keyboard. There are 15 such keys, numbered 1 to 15. Their functions are:
• F3: this is the same as selecting “Copy” from the Edit menu. It will copy the //e screen to the clipboard (including text if in text mode).
• F5: this is the same as selecting “Insert Disk…” from the File menu or clicking the “Insert…” icon.
• F6: this is the same as selecting “Remove Disk…” from the File menu or clicking the “Remove…” icon.
• F7: this is the same as selecting “Preferences…” from the File menu or clicking the “Prefs…” icon.
• option-F7: this is the same as clicking the “Slots…” icon. It opens the preferences and takes you to the slots pane, where you can add or remove Apple II peripherals.
• F8: this is the same as selecting “Save IIe Image…” from the File menu.
• F9: step over instruction (active only when the debugger window is active).
• F10: step into instruction (active only when the debugger window is active).
• F11: step out of instruction (active only when the debugger window is active).
• F12: if the debugger window is not active (the emulator is running and is not being debugged) then this key will interrupt the emulator and control is handed to the debugger - it functions as if you had clicked the Interrupt button. If however the debugger window is active, then F8 will function as if you had clicked the Run button in the debugger window. The overall effect is to alternatively interrupt and execute the CPU.
• F13: this is the same as selecting “Mono/Colour…” from the File menu or clicking the “Mono/colour…” icon. You can also use the option and control keys to select extra options (see Graphics modes below)
• F15: this is the same as clicking the “power switch” icon. Depending on what option the power switch is set to, it will either halt/run the emulator or power-on/power-off the emulator.
Graphics modes
• IIe shows you the //e’s screen in a Mac window. This window should always be located on the same screen as your menu bar. If you have more than one monitor connected, please do not drag the window to a different monitor because IIe does not support multiple monitors.
• normal 40 column text, 40 column lores and “normal” hires graphics can be displayed in either a small 280 * 192 area or in a larger 560 * 384 area. You can alternate between the two sizes by clicking the window’s zoom box.
• 80 column text, 80 column lores and double hires graphics must be displayed in the large 560 * 384 window. You cannot switch to a smaller display whilst any of these modes are active, and activating any of these modes (such as “PR#3 [return]” from BASIC) will make the emulator switch to the larger size.
• clicking the mono/colour icon button changes the display of hires graphics and double hires graphics from monochrome to colour and vice versa. It does not affect text or lores graphics. Naturally, this button does nothing if your Mac’s monitor is set to display black-and-white (1 bit depth).
• clicking the mono/colour icon button whilst holding down the option key changes the depth of the Mac monitor. The depth is rotated from 256 colours (8-bit) to black-and-white (1-bit) to 16 colours (4-bit) and then back to 256 colours (8-bit).
• clicking the mono/colour icon button whilst holding down the control key changes the colour of the monochrome colour. Text is displayed in this colour and so will be affected, as will hires graphics and double hires graphics if the display is set to monochrome (by clicking the mono/colour icon button by itself). Note: control-clicking the icon does nothing if your Mac’s monitor is set to display black-and-white (1 bit depth).
Disk inserting/removing
You can insert different kinds of disks into IIe’s “drives”. They can be real 3 1/2" disks, real ProDOS SCSI hard disk partitions, or disk images - a (Mac) file that “contains” an Apple II “disk”.
Using real disks
Inserting a real 3 1/2" disk
To use a real 3 1/2" disk, run IIe and when the “Apple //e” window is the front window, insert your 3 1/2" disk into any Mac drive. You will be asked if you wish to “insert” the disk into a “drive”, and if so, to select which “drive” to insert it into. Select your drive and you’re set to use that disk.
Note that although you can insert a Mac formatted disk into the disk drive and then have IIe “insert” it into one of its drives, it won’t be very useful. For all practical purposes, you should insert a ProDOS formatted disk into IIe’s drive (see below for info about ProDOS). If you wish to transfer ProDOS files that are on a Mac floppy disk for use in IIe, you should use the “MacProDOS disk” peripheral which allows you to transfer files on a Mac disk or folder directly into ProDOS running on the //e.
Inserting a real ProDOS SCSI hard disk partition
To use a real disk, run IIe. If you have configured a UniDisk into one of the //e’s slots and you have a real ProDOS SCSI hard disk partition on your hard disk, you will usually be asked if you wish to “insert” that ProDOS SCSI hard disk partition into a “drive”, and if so, to select which “drive” to insert it into. Select your drive and you’re set to use that disk.
Using disk images
Introduction
To use a disk image, you need to prepare the file properly before you can “insert” it into a IIe “drive”. A short description of why this is necessary and how to do this follows.
On the Apple II, there are 2 main file systems: DOS 3.3, an older format (and probably the more commoner of the two) which usually supports only 5 1/4" disks; and ProDOS, the newer system which supports different sized disks. The order and format of data on these two systems are completely different from each other, and therefore disk images of disks in these systems are completely different in order and format from each other. As well, there is another file system called Apple Pascal, but isn’t used much (Wizardry is probably the most famous program that used it).
5 1/4" disk images
Most of the disk images of 5 1/4" disks that are available on the internet are in “DOS 3.3” order and are stored as plain compressed (usually gzipped) binary files. They usually have a “.dsk” suffix and are usually 143360 bytes when decompressed. So a typical file is stored as ‘coolgame.dsk.gz’. This is for the benefit of PC users. When you download such a file to your Mac and decompress it, the file is usually of the wrong Macintosh file type and creator (for example, StuffIt Expander decompresses such files to SimpleText text files: type ‘TEXT’, creator ‘ttxt’). To use the disk image file with IIe, you need to change the type to one that IIe can use. The file’s type should be changed to ‘DSK5’ and its creator to ‘AIIe’. When you do this, the file can be double clicked and then opened by IIe.
Dos 3.3 ordered 5 1/4" disk images can also have a suffix of “.do”. Again, change their type/creator to ‘DSK5’/‘AIIe’.
The other possible formats for 5 1/4" disks are:
• “ProDOS” order, usually with a “.po” or “.disk” suffix. Like Dos 3.3 order disks, they are 143360 bytes long. Change their type/creators to ‘DISK’/‘AIIe’ for use in IIe, and
• “nibble” format. These images are usually 232960 bytes long. For example, another Apple II emulator for the Mac called “StopTheMadness” saves to disk images only in “nibble” format. To use them with IIe, change their type/creators to ‘NIBB’/‘AIIe’.
3 1/2" disk images
Most of the 3 1/2" disk images are similar to the 5 1/4" disk images except that they are usually in “ProDOS” order. Aside from that, they are usually stored as plain compressed (usually gzipped) binary files. Again, they usually have a “.dsk” suffix. Again, they’ll have the wrong Macintosh file type and creator. To use the disk image file with IIe, you need to change the type to ‘DSK3’ and its creator to ‘AIIe’. When you do this, the file can be double clicked and then opened by IIe.
For Mac users, a convenient format for 3 1/2" disks is the Apple Disk Copy format. This is the format that is created by disk imaging software such as Apple’s Disk Copy 4.2 or Chad Magendanz’s ShrinkWrap. Such disk images have “ProDOS” ordering. This format is different to the “plain” 3 1/2" disk image that is usually found on the internet. Disk Copy images have an extra 84 bytes of data at the beginning of the image to identify the image’s format. Disk images in this format have the file type ‘dImg’. This does not need to be changed for IIe to use them: you can drag and drop those files onto IIe’s icon. However, if you want to be able to double click the disk image and have IIe open it, you’ll need to change it’s creator to ‘AIIe’. The nice thing about this format is that you can mount these files on your Mac desktop if you have “ProDOS File System” or “PC Exchange” installed: you drag and drop the image on top of “ShrinkWrap” or “DropDisk” and it will mount on your desktop. You can modify the image if you mount it with “ShrinkWrap” but not “DropDisk”.
Note that DiskCopy images that are modified by IIe can be written out to real 3 1/2" disks with DiskCopy since the checksums are updated when you remove the disk image from the drive or when you quit IIe.
Hard disk images
Finally, there are disks stored in hard disk volume format. They usually have a “.hdv” suffix. They are ProDOS ordered files and are usually images of Apple II hard disks. There are in fact two hard disk formats. The more common one is a ‘plain’ image, much like the plain floppy disk image mentioned above. Such images usually start with the hex bytes “01 B0 03” (use Norton Disk Editor to see this). These images should have file type ‘hdrv’ and creator ‘AIIe’ - the same as that used by ShrinkWrap 2.0 and ImageMaster 1.0. If instead the image starts with the text “SimSystem” then it should have file type ‘HDV ’ (note the space after the “V”) and creator ‘AIIe’.
Changing file types and creators
If you download your files from the internet or you get them in compressed format (you can tell because the files end in “.gz” or “.zip”) then it’s quite easy to decompress them properly. I recommend using Internet Config 1.2, DropStuff with Expander Enhancer 4.0 or later, and StuffIt Expander 4.0 or later, since the combination of these programs can decompress the files correctly when you set up Internet Config for suffix mapping.
To do this, run Internet Config and click “File Mappings”. Then add the file extensions “.dsk”, “.do”, and “.po”. For each of them, click the “binary data” (and not “Macintosh”) button. Then for “.dsk” and “.do” files, map them as File Type ‘DSK5’ and File Creator ‘AIIe’. For “.po” files, map them as File Type ‘DISK’ and File Creator ‘AIIe’. Save your changes. StuffIt Expander will now be able to correctly decompress the files.
Next, configure your transfer program (be it an ftp client or a WWW client) so that files ending in .gz, .zip, .dsk, .do, and .po are downloaded as binary data and not text.
Next, if the file ends in .gz or .zip, decompress the file by dragging and dropping it on StuffIt Expander. They will be decompressed and come out as ready-to-use IIe disk images which you can double click to insert them into IIe.
To manually change a file’s type or creator, use a file type editor such as ResEdit (free from Apple), BunchTyper (free), FileTyper (shareware), or Aladdin’s Desktop Tools (good quality commercial utility [biased opinion]).
How to insert and remove disks and disk images
After the disk image file is set up for use, there are several ways you can load it into IIe:
• you can drag it to IIe’s icon in the Finder,
• you can double click the disk image (if its creator is set to ‘AIIe’),
• you can select “Insert Disk Image…” from the File menu (or click the “Insert…” icon button),
• you can drag the disk image to the drive you want to insert it into. If the image can be loaded into that drive, the drive image’s name will highlight when you drag the image over it; note that this only works in you are running System 7.5 or later, or have Macintosh Drag and Drop installed in pre-7.5 systems, and
• you can click the drive image name of the drive that you want to load the image into. An open file dialog will then ask you to select the image to load.
IIe supports two 5 1/4" drives and two to four 3 1/2" drives for each installed disk drive “card”. You can have four 3 1/2" drives only if the UniDisk card is installed in slot 5, and the last two drives can only be available in ProDOS 2.0 or later.
You can remove disks by selecting “Remove Disk Image…” from the File menu or click the “Remove…” icon button. In the dialog that appears, select which disks you want to remove and click Remove. Note that you do not need to remove a disk before inserting a new one; newly inserted disks displace disks that are already in that drive (that is, the old one is automatically removed for you).
Loading and saving information - memory images
The best way to load and save your data is by saving it to a disk or disk image, which is done by selecting the save command in the Apple II program. However, there are some programs that don’t let you save but there are times that you need to save what you’re doing and return to it later - for example, you’ve spent the last 3 hours playing Lode Runner and you a wedding to go to. To solve this problem, IIe allows you to save its current state by the use of “memory images”. In a nutshell, this operation takes a “snapshot” of the //e’s memory and saves it on disk, where it can later be restored.
Note that the size of the saved image will be the size of the current //e memory including any extra auxilary memory you have allocated to the RamWorks III card. So if you have set up a //e with 1 Mb of auxilary memory, the saved image will be 64K (main memory) + 1024K (aux memory). IIe will not save the contents of any Memory Card you install in a slot however.
When you ask IIe to load a memory image, it first checks that the size of the saved image is the same as the current memory setup. If it is, it loads it in and restores the //e to the saved state. Of course, you lose whatever you had in the //e’s memory. You will not be warned of this loss because IIe assumes you know what you’re doing when you open the memory image. If the memory image’s size does not match the current memory setup, then IIe will offer to load in only the first 128K or to cancel the load operation, and it will tell you what you need to set the memory size to if you want to load the whole image.
Emulator instructions
This section covers topics related to the use of the emulator and its peripherals.
Default settings
The default settings for IIe are:
• small screen
• no change in depth
• colour mode
• does not draw directly to your screen
• 1MHz speed
• 64K only of auxillary memory
• produces soft sounds
• no ‘delete’ key translation
• no type-ahead buffer
• soft caps lock disabled
• joystick emulation via the keypad
• fast disk reads and writes
• ask what to do if a ProDOS hard disk is found
• the default Mac-ProDOS folder is the folder that the IIe program is in
• Disk II in slot 6 (fixed)
• 80 column card in slot 3 (fixed)
• no other cards installed
Starting up the emulator
If you start IIe with a disk (by double clicking the disk image’s icon or by dragging it to IIe’s program icon), the emulator will start running as soon as it is ready and the disk is “inserted”.
However, when you start IIe without any disks in any drive, the emulator won’t run until you tell it to. You can start it up by clicking the “Run/Stop” icon button. Pressing it again will stop it. Alternatively, you can press F15. The icon will change to show you the state of the emulator. Of course, it isn’t very useful without a disk…
Bonus: if you start IIe up with the command and option keys held down, then IIe will use the title of the //e window to show you how many 65c02 clock cycles it has emulated in each of its emulation cycles (which are about half a second long).
The Reset key
To “reset” the //e, that is, simulate the pressing of the reset key on a real //e, press control-delete (the delete key here acting like the reset key) or the “Reset” icon button. Tip: to force a “cold” reboot, press command-control-delete or command-click the “Reset” icon button. If you want to see the //e diagnostic test, press option-control-delete (or option-click the “Reset” icon button) (but the test is kind of boring in my opinion…)
The Keyboard
When the emulator is running, all keystrokes are directed to the //e window. When the emulator is not running, all keystrokes are directed to the IIe program, that is, the menu bar or the frontmost window. So if you press command-I to insert a new disk and nothing happens, be sure that the emulator is not running. If it is running, press control-esc or F15 or the “Run/Stop” icon button, to first halt it and then press command-I (or just click the “Insert…” icon button if you don’t want to stop the emulator).
The ‘delete’ key on the Mac keyboard can be configured to produce either a ‘backspace’ or a ‘delete’ key on the //e.
IIe implements a type-ahead buffer so you won’t lose keystrokes but some programs (especially games) don’t respond with this on so you may have to turn it off. For text editors and word processors, you’ll probably want to turn it on.
The Tab key can be configured as a ‘soft caps lock’ key. If configured as such, then when you first press it, it changes any key you type from uppercase to lowercase and vice versa. When pressed again, it does not change the keys. In other words, it acts just like the real ‘caps lock’ key but the changes apply only to //e. This allows you to keep the real ‘caps lock’ key in your preferred position without having to change it every time you use another Mac program.
Paddles and buttons
The paddles/joystick is emulated by the use of either the Mac keypad or the mouse. If you have a joystick or gamepad attached to your Mac, you should set it to simulate the keypad.
If the keypad is selected to emulate the joystick, then:
• Keypad 7 is the same as pushing the joystick to the top-left
• Keypad 3 is the same as pushing it to the bottom-right
• Keypad 1 pushes it to the bottom-left
• Keypad 9 pushes it to the top-right
• The other keypad keys push it in between the corners
This arrangement works quite well - most programs have no problems with it.
If the mouse is selected to emulate the joystick, then moving the mouse around the screen will move the joystick in the same direction. You can configure the mouse paddle values to be based on the mouse’s screen position or its position within the //e window.
This emulator uses a “smart” paddle emalation routine (technical weenies: it counts clock cycles), so all paddle/joystick reading programs should work. If you find a program that doesn’t work well, let me know and I’ll investigate it.
The “open” and “closed” apple keys on the //e keyboard (paddle 0’s button and paddle 1’s button respectively), as well as the third paddle button are supported. The Mac keys to use are command, option and shift respectively.
Debugger instructions
Important: most people will not need to read this section for ordinary use of IIe. This section covers the use of the debugger which is a tool for seeing what the //e is doing at the machine instruction level.
If you end up in the debugger and don’t know what to do, try clicking the Run button. If it fails, try clicking the Reset button. If that fails, you’ll have to power down the //e or quit IIe and restart it.
Currently the debugger is in a “raw” state, ie, incomplete and rough at the edges. However, you can use it to do some interesting things such as:
• set a breakpoint
• step an instruction
• step over an instruction
• step over all instructions in a loop and stop at the end of a loop
• step over all instructions in a 65c02 subroutine and stop at the point after the caller routine called the subroutine
• break on interrupts
• reset the //e
• run the //e
• disassemble memory
• change memory and the 65c02 registers
Oops. I’ll get around to writing this section for the next release. Let’s say that learning about the debugger “is left as an exercise for the reader” :-)
